Shareware Grab Bag/Shareware Grab Bag.iso/011/xray2.arc/XRAY.DOC

Text File | 1985-12-14 | 10.5 KB | 239 lines

XRAY.COM, the PC Background Monitor

    YARP: Yet Another (DOS) Resident Program.  So what makes this one
    special?

    What is XRAY?

    XRAY is a tool that allows you to monitor areas of your computer's
    memory while other programs are running.  These other programs can
    be COMMAND.COM, for those interested in some aspect of that program;
    your own resident programs; or some .COM or .EXE application.  XRAY
    gives you, on a real-time basis, the ability to watch memory variables
    or your stack change dynamically.



    How would I best use XRAY?

    I typically use XRAY in combination with DEBUG.COM.  Probably the
    the most difficult thing to find with DEBUG when tracing through code
    is which subroutines are corrupting the stack.  To find this, one must
    dump the stack, inspect the values carefully or make a hardcopy, set
    the desired breakpoint, and then redump the stack and compare.  This
    becomes extremely time consuming if your program is highly stack inten-
    sive as are C or Pascal programs.  XRAY allows you to watch the stack
    as you trace and break.  Armed with a MAP, DEBUG, and XRAY, the culprit
    module can be quickly found and fixed.

    Another use for XRAY is debuging resident programs.  If you have a
    program which is intended to be used under some other applications,
    XRAY will let you watch its variables and the like change as you test
    it.  For instance, the original version of XRAY simply loaded,
    printed its SEGMENT:OFFSET value and terminated but remained resident.
    To invoke the window or set the display address of the window a second
    program had to be run.  After monitoring the keyboard data areas
    and seeing how Shift, Alt, Cntl, etc. keys were being handled, I imp-
    lemented the mechanism for invoking XRAY that it has now: Alt/Left-Shft.

    I also had some stack-size problems with XRAY originally and used XRAY
    to find these problems by watching the stacks overflow.  Without using
    XRAY it would have been a trial-and-error guessing game.  With XRAY
    it was a quick fix!

    XRAY's main concept is to monitor memory while the system is running,
    and this is where XRAY's use is unparalleled.  Whether you are writing
    a multitask dispatcher, a resident keyboard handler/enhancer, or a COBOL
    mailorder program, XRAY can help you find problems easily, where in the
    past a vigorous trace-n-break-n-dump session with DEBUG.COM, or some
    similar debugger, was required.  Once you get the hang of it, XRAY will
    prove to be a valuable addition to your arsenal.

    Why did you write this program?

    I wrote XRAY because I use DEBUG.COM daily and needed a little more
    than DEBUG had to offer.  I do have several other debuggers at my
    disposal, and no doubt they have some great features, but I have yet
    to find one with this window feature.  I was tempted to write a full
    debugger in the beginning, but decided against it since DEBUG really
    does quite nicely under most circumstances: it comes with DOS, it has
    simple commands, and it will do most everything you need a debugger to
    do.  Because of that, I decided to simply write something to (where's
    the) "beef" it up a tad:  XRAY.  After XRAY was written, it turned out
    to have more uses than I originally planned.  Fine.  In fact, great.
    Still, my original goal was accomplished.


    Are there any outstanding bugs that you know of?

    XRAY has been tested on an IBM PC, PC/XT, PC/AT, Zenith HS-150, Compaq,
    IT&T, and the MAD computers.  So far, so good.  The only problem I've
    encountered is with the IBM CGA (Color Graphics Adapter).  With this
    piece of hardware XRAY causes the screen to flicker and "snow."  This
    is because XRAY accesses the video regen buffer directly and does not
    disable the CRT or check for vertical retrace from the 6845 CRT chip.
    For those of you who use this card, ever notice the "flicker" you get
    when text is scrolling off the screen?  This comes from the ROM video
    support which disables (i.e. turns off) the monitor while it accesses
    the video regen memory.  If this were done in XRAY--and I did try it,
    incidently--the screen would flash badly constantly, and you'd have a
    headache quicker than you could say XRAY.  XRAY still functions
    ok, just has the flickering.  Wish I could change it.  If someone knows
    how let me know.

    How do I bring up the XRAY window?

    Press down the Alt and Left Shift keys simultaneously.


    Could you explain each of the features of XRAY?

    Gladly.

    1.) Sleep/Wake  Up

        This is the mechanism used to invoke XRAY's display window.
        After XRAY is first loaded the default is Sleep.  To Wake Up
        XRAY you press Alt+Left-Shift whichs brings up the main menu,
        position the selection bar over Sleep, and hit Return.   Next
        press Esc to put the menu away and start the XRAY display.  To
        put the window away bring the menu up as before, position the
        selection bar over Wake  Up, press Return, and then presss Esc.
        The XRAY window will go away and the text underneath it will be
        restored.

    2.) Set Scroll

        This feature allows you to scan a segment of memory.  The
        default setting is None--no scrolling.  To change this bring
        up the XRAY main menu, position the selection bar over Set
        Scroll, and press Return.  This will bring up a second, smaller
        menu with these choices:
                    None
                    Slow
                    Fast

        None: leave the window focused on the same area of memory.
        Slow: display 18 bytes (one line) farther in memory each second.
        Fast: display 288 bytes (18 lines) farther in memory per second.

        This allows you to seach for a given location to display, or
        to constantly circulate through a segment of memory.  When the
        top of the memory segment is reached (hex FFFF) the display will
        circulate back to 0.

        To select, position the selection bar and press Return.  Esc can
        be pressed alone to exit the menu without changing the current
        selection.

        Hint:  to use scroll to search for the area you need, turn on
        Slow or Fast and keep your fingers near Alt and Left-Shift.
        When you see the desired memory area bring up the XRAY window
        and turn off scrolling.

    3.) Window  Size

        This feature allows you to change the size of the XRAY window
        from 1 to 20 lines of display.  Simply position the selection
        bar, press Return, use + (plus) to increase the size, use -
        (minus) to decrease the size, use Esc to put the size-selection
        box away.

        Note:  the larger the window the more time XRAY will use during
        its time slice.  If you are running a program which depends on
        tight timing, I suggest you set the window to the minimum number
        of lines you can get by with.


    4.) Change Address

        This is how you change the location of the memory window.  The
        default is 0040:0000 (SEGMENT:OFFSET), which happens to be the
        ROM BIOS memory area on an IBM, and fully compatible, PC.  To
        change this (note that the scroll feature also will change the
        memory window display) position the selection bar and press
        Return.  Now you can enter any hex digits for the new address,
        can move to the desired digit to change or skip over digits
        with the right and left arrows, can skip from segment to offset
        or vice versa with the tab key, or end the edit by pressing
        Return or the up arrow key.

    5.) Current Location

        This is the segment:offset address where control will return
        when XRAY is done updating its display window.  This selection
        is invoked and changed like the Set Scroll selection:  position
        the selection bar and press Return, invoking a second smaller
        window like:
                All
                None
                Mine

        All:  display all return addresses.
        None: do not display any return addresses.
        Mine: display only addresses that have the segment I enter.

        All is the default at load time, and will display every return
        address on the stack.  None will cause XRAY to not update the
        return address.  Mine will invoke a subordinate window where
        you are allowed to enter the segment for the return addresses
        you wish to see.  The return address is only updated if its
        segment matches the one you've entered.

        Note:  this feature is useful if you suspect your program is
        stuck in an endless loop, or to find what section of code is
        getting executed the most.

        Like a large window size, when Current Location is enabled
        XRAY will use more time during its time slice.  Disable (select
        None) if you are running a time-critical program.

    6.) Unhook  XRAY

        This selection tells XRAY to unhook itself from the interrupt
        vectors and deallocate the memory it occupies, thereby putting
        the machine back to the state it was in before you loaded XRAY.

        To select, position the selection bar and press Return.

        WARNING:  do not Unhook XRAY while you are running another
        program.  DOS maintains a free-memory linked list which gets
        destroyed if XRAY is unhooked while another program has memory
        allocated for itself.  If you want to see what I mean without
        hurting anything do this:
                a.) Load XRAY
                b.) Run CHKDSK.COM and look at Free Memory Size
                c.) Run DEBUG.COM
                d.) Bring up the XRAY menu and Unhook XRAY
                e.) "Q"uit out of DEBUG.COM (if not already)
                f.) Run CHKDSK.COM and look at Free Mem Size
                    (It will be different--alot smaller)
                g.) Reboot.

    Caveats:

        If you are using XRAY with other resident programs--like
        Borland's Sidekick--I suggest you load XRAY after these other
        programs.  XRAY filters certain interrupt vectors, but always
        passes control on to the handler that was in the filtered vector
        when XRAY loaded.  Some of these other resident programs do not
        do that and thereby will hang XRAY.  I found, for instance, if
        Sidekick is loaded first and XRAY second there are no problems.
        If XRAY is loaded first and Sidekick second, Sidekick hangs XRAY
        when the main menu is invoked--not very nice.

        Also, if you are going to Unhook XRAY, or unhook any other
        resident program for that matter, make sure everything that
        was loaded after the program to unhook has been unhooked.  For
        instance, if you load Sidekick and then XRAY and then want to
        unhook Sidekick, first Unhook XRAY to keep the free-memory list
        intact.



        Thank You for using XRAY.COM, the PC Background Monitor.
        I hope XRAY is a pleasure for you to use.


        John F. Ferguson II.